// Copyright  2004-2008 Backplane Ltd.
//
// This file is part of Ubiquity formsPlayer
//
// Ubiquity formsPlayer is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the
// Free Software Foundation; either version 3 of the License, or (at your
// option) any later version.
//
// Ubiquity formsPlayer is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
// FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
// more details.
//
// You should have received a copy of the GNU General Public License
// along with Ubiquity formsPlayer If not, see <http://www.gnu.org/licenses/>.
//	
//
//   Purpose:  .
//   $Id$


class IUISelection
{
//	This interface is intended to allow programmers to 
//	add selectable items to selection controls.
//		like selectOne and selectMany (select1 and select)
public:
	//appends an item after the last item of id "sId"
	//if bClear is true, removes them all first.
	virtual HRESULT AddItem
	(
		const BSTR sId,			//ID of the item to put or modify
		const BSTR sCaption,	//Caption to put
		const BSTR sValue,		//Value to put
		const BSTR sParentId,	//ID of the choices group to put the item into (if any)
		const bool bClear		//Whether to remove all options with that ID (for itemset.)
	) = 0;


	//The default last value in the following methods is 
	//	to allow users to not have to specify an index when
	//	they intend to access the only one in a list.

	//removes the item at index in the list of items with id
	//-1 removes them all.
	virtual HRESULT RemoveItem
	(
		const BSTR id,
		const long index = 0
	) = 0;

	//puts the caption/value text at the specified node.
	virtual HRESULT put_ItemCaption
	(
		const BSTR id,
		const BSTR caption,
		const unsigned long index = 0
	) = 0;
	virtual HRESULT put_ItemValue
	(
		const BSTR id,
		const BSTR value,
		const unsigned long index = 0
	) = 0;
};
